<HTML><HEAD><TITLE>EplexInstance:eplex_get(++ParamName, -Value)</TITLE>
</HEAD><BODY>[ <A HREF="index.html">library(eplex)</A> | <A HREF="../../index.html">Reference Manual</A> | <A HREF="../../fullindex.html">Alphabetic Index</A> ]
<H1>EplexInstance:eplex_get(++ParamName, -Value)</H1>
Retrieve information about solver state and results for eplex instance EplexInstance.
<DL>
<DT><EM>ParamName</EM></DT>
<DD>Name of parameter (atom)
</DD>
<DT><EM>Value</EM></DT>
<DD>Returned value for ParamName
</DD>
</DL>
<H2>Description</H2>
<P>
   Retrieve information about solver state and the logically most recent
   results for the eplex instance <TT>EplexInstance</TT>. <TT>ParamName</TT> 
   is the same as that for lp_get/3, which retrieves the same information 
   via the solver state.
</P>

<DL>
<P>  
     <DT><STRONG><TT>vars</TT></STRONG>
     <DD>Returns a term ''(X1,...,Xn) whose arity is the number of
         variables involved in the solver's constraint set, and whose
         arguments are these variables.

<P>
     <DT><STRONG><TT>ints</TT></STRONG>
     <DD>Returns a list [Xi1,...,Xik] which is the subset of the problem
         variables that the solver considers to be integers.

<P>
     <DT><STRONG><TT>constraints_norm</TT></STRONG>
     <DD>Returns a list of the problem constraints (excluding any cutpool
         constraints) in normalised form.  They may be simplified with
         respect to the originals that were passed to the problem.

<P>
     <DT><STRONG><TT>constraints</TT></STRONG>
     <DD>Returns a list of the problem constraints (excluding any cutppol
         constraints) in denormalised (readable) form.  They may be
         simplified with respect to the originals that were passed to the
         problem.

<P>
     <DT><STRONG><TT>objective</TT></STRONG>
     <DD>Returns a term min(E) or max(E), representing objective function
         and optimisation direction. E is a linear expression: any
         quadratic components will not be retrieved.

<P>
     <DT><STRONG><TT>num_cols</TT></STRONG>
     <DD>Returns the number of columns (i.e. variables) in the matrix of the
     solver state.

<P>
     <DT><STRONG><TT>num_rows</TT></STRONG>
     <DD>Returns the number of rows (i.e. constraints) in the matrix of the
     solver state.

<P>
     <DT><STRONG><TT>num_nonzeros</TT></STRONG>
     <DD>Returns the number of non-zero coefficients in the matrix of the
     solver state.

<P>
     <DT><STRONG><TT>num_ints</TT></STRONG>
     <DD>Returns the number of columns (i.e. variables) constrained to be
     integers in the matrix of the solver state.

<P>
     <DT><STRONG><TT>num_quads</TT></STRONG>
     <DD>Returns the number of non-zero coefficients in the quadratic
     coefficient matrix (Q-matrix) of the solver state.

<P>
     <DT><STRONG><TT>method</TT></STRONG>
     <DD>Returns the method that is specified to solve the problem. If an
     auxiliary  method can be given for the method, and this auxiliary
     method is not <TT>default</TT>, the method will be returned as 
     Method(Aux), e.g. <TT>barrier(none)</TT>. The method will be 
     <TT>default</TT> unless otherwise specified by the the user (at setup or 
     via eplex_setup/2 or lp_setup/3).
     In case of MIP solving, this is the start algorithm (the one that 
     is used to solve the initial relaxation).

<P>
     <DT><STRONG><TT>node_method</TT></STRONG>
     <DD>Applicable to MIP problems only. Returns the method that is
     specified to solve the problem at the nodes of the branch-and-bound
     tree. If an auxiliary method can be given for the method, and this
     auxiliary method is not <TT>default</TT>, the method will be returned
     as Method(Aux), e.g. <TT>barrier(none)</TT>. The method will be
     <TT>default</TT> unless otherwise specified by the the user (at setup
     or via eplex_setup/2 or lp_setup/3).
     Note that the method for solving the root (initial relaxation) node
     is specified by <TT>method</TT>.

<P>
     <DT><STRONG><TT>status</TT></STRONG>
     <DD>Status that was returned by the most recent invocation of the 
         external solver.

<P>
     <DT><STRONG><TT>cost</TT></STRONG>
     <DD>Objective value (i.e. cost/profit) of the current solution.
         Fails if no solution has been computed yet.

<P>
     <DT><STRONG><TT>best_bound</TT></STRONG>
     <DD>The best bound (for minimisation, the lower bound) on the optimal 
         objective value for the current problem. Together with the
         worst_bound, this specify the range for the optimal objective
         value. Note that a non-empty range does not mean that the problem
         is feasible unless an objective value (cost) is also
         available. The best_bound is the same as the current objective
         value if the problem have been solved to optimality. It can be
         better than the objective value either because a) (for MIP
         problems only) the problem have been optimised to within the
         mipgap tolerance, or b) the problem was not solved to optimality,
         i.e. it was aborted before the optimal solution was found.
<P>
     <DT><STRONG><TT>worst_bound</TT></STRONG>
     <DD>The worst bound (for minimisation, the upper bound) on the optimal 
         objective value for the current problem. Together with the
         best_bound, this specify the range for the optimal objective
         value. Note that a non-empty range does not mean that the problem
         is feasible unless an objective value (cost) is also
         available. The worst_bound is the same as the current objective
         value if a solution have been computed for the problem, whether
         the problem was solved to optimality or not. Depending on the 
         problem type and method used to solve the problem, a worst bound
         can be returned for a problem even if the solving of the problem
         was aborted before a solution was obtained. 
<P>
     <DT><STRONG><TT>typed_solution</TT></STRONG>
     <DD>Returns a term ''(X1,...,Xn) whose arguments are the properly
         typed (integer or float) solution values for the corresponding
         problem variables (<TT>vars</TT>).  The floating point solutions
         are the same as returned by <TT>solution</TT>, the integers are
         obtained by rounding the corresponding floating-point solution to
         the nearest integer.  To instantiate the problem variables to
         their solutions, unify this term with the corresponding term
         containing the variables. Note that this unification could fail
         if two problem variables Xa and Xb were unified after the solution 
         was lasted computed, as the solutions values in the Xa and Xb
         positions could be different, even though they are now represented 
         by one variable.
         Fails if no solution has been computed yet.

<PRE>
    instantiate_solution(Handle) :-
        lp_get(Handle, vars, Vars),
        lp_get(Handle, typed_solution, Values),
        Vars = Values.
</PRE>

<P>
    <DT><STRONG><TT>slack</TT></STRONG>
    <DD>Returns a list of floating-point values representing the constraint
        slacks in the logically last solve. The problem consists of normal
        constraints followed by any added cutpool constraints, and the
        order corresponds to the list order in <TT>constraints</TT> for
        normal constraints, and to cutpool_info(last_added,Info) for the
        cutpool constraints.  Fails if no solution has been computed yet.

<P>
    <DT><STRONG><TT>slack(Indexes)</TT></STRONG>
    <DD>Returns a list of floating-point values representing the slack
        values for the constraints represented by Indexes. Indexes are a
        list of constraint indices (as returned by lp_add_constraints/4 for
        normal constraints, and lp_add_cutpool_constraints/4 for cutpool
        constraints), and the order of the returned list corresponds to the
        order in <TT>Indexes</TT>.  Fails if no slack value has been
        computed yet for any of the constraints in Indexes -- note that 
        values are only computed for cutpool constraints if they were added
        to the problem.

<P>
    <DT><STRONG><TT>dual_solution</TT></STRONG>
    <DD>Returns a list of floating-point values representing the dual
        solutions in the logically last solve. The problem consists of
        normal constraints followed by any added cutpool constraints, and
        the order corresponds to the list order in <TT>constraints</TT> for
        normal constraints, and to cutpool_info(last_added,Info) for the
        cutpool constraints.  Fails if no solution has been computed yet.

<P>
    <DT><STRONG><TT>dual_solution(Indexes)</TT></STRONG>
    <DD>Returns a list of floating-point values representing the dual
        solutions for the constraints represented by Indexes. Indexes are a
        list of constraint indices (as returned by lp_add_constraints/4
        normal constraints, and lp_add_cutpool_constraints/4 for cutpool
        constraints), and the order of the returned list corresponds to the
        order in <TT>Indexes</TT>.  Fails if no dual solution has been
        computed yet for any of the constraints in Indexes -- note that
        values are only computed for cutpool constraints if they were added
        to the problem.

<P>
    <DT><STRONG><TT>constraints(Indexes)</TT></STRONG>
    <DD>Returns a list of problem constraints as specified by
        Indexes in denormalised form. The constraints can be either 
        normal constraints or cutpool constraints.
<P>
    <DT><STRONG><TT>constraints_norm(Indexes)</TT></STRONG>
    <DD>Returns a list of problem constraints as specified by
        Indexes in normalised form. The constraints can be either 
        normal constraints or cutpool constraints.
<P>
    <DT><STRONG><TT>cutpool_info(Select,Info)</TT></STRONG>
    <DD>Returns the information specified by Info for the cutpool constraints
        specified by Select. The returned information is either
        i) a pair of lists Indexes-Values where Indexes is the index for
        the constraint in the corresponding position of Values, or 
        ii) a list of Indexes if the information requested is index. Info 
        can be:
<DL>
           <DT><STRONG><TT>index</TT></STRONG>
               <DD>the indexes for the selected constraints. A list
                   of Indexes are returned.
           <DT><STRONG><TT>active</TT></STRONG>
               <DD>the current active status of the selected constraints. 
                   The status is either 0 (not active) or 1 (active).
                   A pair of lists Indexes-ActiveStatus is returned.
           <DT><STRONG><TT>add_initially</TT></STRONG>
               <DD>the current add_initially status of the selected 
                   constraints. The status is either 0 (not add) or 1 (add).
                   Note that although inactive constraints have a
                   add_initially status, they will not be added to a problem.
                   A pair of lists Indexes-AddInitially is returned.
           <DT><STRONG><TT>binding_state</TT></STRONG>
               <DD>the binding state for the selected constraints in the
                   logically last solve for the problem. A pair of lists
                   Indexes-BindingStates is returned. To get this
                   information, the slack values must be available from the
                   last solve.
                   The state can be:
                   a) binding - the constraint was satisfied and binding, i.e.
                      it is within tolerance of its RHS value in the
                      normalised form. 
                   b) satisfied - the constraint was satisfied but not
                      binding. 
                   c) inactive - the constraint was inactive.
           <DT><STRONG><TT>constraints_norm</TT></STRONG>
               <DD>the normalised form of the constraints for the selected 
                   constraints is returned in a pair of lists 
                   Indexes-Constraints.
           <DT><STRONG><TT>constraints</TT></STRONG>
               <DD>the denormalised form of the constraints for the selected 
                   constraints is returned in a pair of lists 
                   Indexes-Constraints.
</DL>

    The constraints are selected by Select, which can be:
<DL>
           <DT><STRONG><TT>cstr(Idx)</TT></STRONG>
               <DD>The cutpool constraint as specified by <TT>Idx</TT>. 
           <DT><STRONG><TT>group(Name)</TT></STRONG>
               <DD>The cutpool constraints in the group <TT>Name</TT>. Both
                   active and non-active constraints are returned. Note that
                   the name of the default group is the atom nil (<TT>[]</TT>).
           <DT><STRONG><TT>last_added</TT></STRONG>
               <DD>The cutpool constraints that were added to the
                   problem in the logically previous solve of the problem. 
                   The constraints were either added initially, or were
                   added because they were violated in an intermediate
                   invocation. 
           <DT><STRONG><TT>last_notadded</TT></STRONG>
               <DD>The cutpool constraints that were not added to the
                   problem in the logically previous solve of the problem,
                   i.e. they were not violated.
           <DT><STRONG><TT>last_inactive</TT></STRONG>
               <DD>The cutpool constraints that were inactive during the
                   logically last solve of the problem. This does not
                   include any constraints that were added since the last
                   solve. 
</DL>
<P>
    <DT><STRONG><TT>demon_tolerance</TT></STRONG>
    <DD>Returns a comma-separated pair <TT>(RealTol,IntTol)</TT> of
        floating-point values which specify how far outside a variable's
        range an lp-solution can fall before lp_demon_setup/5
        re-triggers. The tolerances differ for real (default 0.00001) and
        integer (default 0.5) variables.

<P>
    <DT><STRONG><TT>simplex_iterations</TT></STRONG>
    <DD>Returns the external solver's count of simplex iterations.

<P>
    <DT><STRONG><TT>node_count</TT></STRONG>
    <DD>Returns the external MIP solver's node count. Note that this may 
        or may not include the initial root node.
<P>
    <DT><STRONG><TT>statistics</TT></STRONG>
    <DD>Returns a list of counter values <TT>[Successes, Failures,
        Aborts]</TT>, indicating how often lp_solve/2 was invoked on the
        Handle, and how many invocations succeeded, failed and aborted
        respectively.

<P>
    <DT><TT>timeout</TT></STRONG>
    <DD>Returns the time-out value for the solver state. This is the amount
        of CPU time in seconds that the external solver will be allow to
        spend solving the problem before timing out. The value is 0 if 
        no time-out has been set.
<P>
     <DT><STRONG><TT>optimizer_param(Param)</TT></STRONG>
     <DD>Returns the value of the external solver's parameter Param
         for the problem represented by Handle. The external solver 
         has a number of parameters that affect the way they work, and 
         this queries their values. If Param is not a valid parameter for
         the solver, an out of range exception is raised. See below for 
         more details on the parameters.
<P>
    <DT><STRONG><TT>post_equality_when_unified</TT></STRONG>
    <DD>Returns the value (yes or no) if an equality constraint will be
        posted to a solver if two variables in the solver's problem are 
        unified. 
<P>
    <DT><STRONG><TT>pool</TT></STRONG>
    <DD>Returns the name of the eplex instance (if any) associated with 
        the solver state. Fails otherwise. Only useful if called with 
        lp_get/3.
<P>
    <DT><STRONG><TT>handle</TT></STRONG>
    <DD>Returns the solver state handle (if any) associated with the eplex 
        instance. Fails otherwise. Only useful if called with eplex_get/2.
<P>
</DL>
Note that reduced_cost, slack, dual_solution can only be retrieved
when previously requested in the option list of lp_setup/4 or with lp_set/3.
An out of range error will be raised otherwise.

<P>
For the external solver's control parameter specified by
optimizer_param(Param), Param must be an atom. The Value returned is
either an integer, float or atom, depending on the parameter. The parameter
is generally specific to a solver and version, and also, they may be
problem specific, or global, again depending on the solver version. In all
cases, the value returned by lp_get/3 is the current value for the parameter
for the problem Handle. Refer to the solver documentation for details on the 
parameters. The names of the parameters are derived from the names of the 
parameters in the external solver. For CPLEX, take the parameter name from 
the CPLEX manual (or cplex.h), remove the CPX_PARAM_ prefix and convert the 
rest to lower case, e.g.

<PRE>
        CPX_PARAM_NODELIM becomes nodelim. 
</PRE>
For XPRESS-MP (version 13 and newer), take the parameter name from the 
manual (or xpresso.h), remove the XPRS_ prefix (if present) and convert 
the rest to lower case, e.g.
<PRE>
	XPRS_MAXNODE becomes maxnode. 
</PRE>
<P>
For solvers used via the OSI, there are a few generic parameters supported 
via OSI, and depending on the actual solver, there may be some additional
solver-specific parameters. For the generic parameters, take the parameter
name, remove the Osi prefix and convert the rest to lower case, e.g.
<PRE>
        OsiPrimalTolerance becomes primaltolerance
</PRE>

<P>
    The following parameter names are additional aliases that work for
    several solvers:
<DL>
    <DT><TT>feasibility_tol</TT>
	<DD>CPX_PARAM_EPRHS (CPLEX) or XPRS_FEASTOL (XPRESS-MP) or
            OsiPrimalTolerance (OSI) - float
    <DT><TT>integrality</TT>
	<DD>CPX_PARAM_EPINT (CPLEX) or XPRS_MIPTOL (XPRESS-MP) or
            CbcIntegerTolerance (OSI,Cbc specific) - float
    <DT><TT>iteration_limit</TT>
	<DD>CPX_PARAM_ITLIM (CPLEX) or XPRS_LPITERLIMIT (XPRESS-MP) or
            OsiMaxNumIteration (OSI) -integer
    <DT><TT>node_limit</TT>
	<DD>CPX_PARAM_NODELIM (CPLEX) or XPRS_MAXNODE (XPRESS-MP) or
            CbcMaxNumNode (OSI, Cbc specific) -integer
    <DT><TT>objdifference</TT>
	<DD>CPX_PARAM_OBJDIF (CPLEX) or XPRS_MIPADDCUTOFF (XPRESS-MP) or
            CbcCutoffIncrement (OSI, Cbc specific) - float
    <DT><TT>refactor</TT>
	<DD>CPX_PARAM_REINV (CPLEX) or XPRS_INVERTFREQ (XPRESS-MP) -integer
    <DT><TT>scrind</TT>
	<DD>CPX_PARAM_SCRIND (CPLEX) or XPRS_OUTPUTLOG (XPRESS-MP) -integer
</DL>

            
<H3>Exceptions</H3>
<DL>
<DT><EM>(5) type error </EM>
<DD>EplexInstance does not a solver setup for it.
<DT><EM>(40) stale object handle </EM>
<DD>Solver state had been previously destroyed.
</DL>
<H2>See Also</H2>
<A HREF="../../lib/eplex/eplex_solver_setup-4.html">eplex_solver_setup / 4</A>, <A HREF="../../lib/eplex/eplex_set-2.html">eplex_set / 2</A>, <A HREF="../../lib/eplex/lp_set-3.html">lp_set / 3</A>, <A HREF="../../lib/eplex/lp_get-3.html">lp_get / 3</A>, <A HREF="../../lib/eplex/lp_add_constraints-4.html">lp_add_constraints / 4</A>
</BODY></HTML>
